SGI Freeware 1998 November/Freeware November 1998.img/dist/fw_emacs.idb/usr/freeware/info/ediff-1.z/ediff-1

GNU Info File | 1998-10-27 | 48KB | 848 lines

This is Info file ../info/ediff, produced by Makeinfo-1.63 from the
input file ediff.texi.
   This file documents Ediff, a comprehensive visual interface to Unix
diff and patch utilities.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
File: ediff,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
* Menu:
* Introduction::                About Ediff.
* Major Entry Points::          How to use Ediff.
* Commands::                    Ediff commands.
* Registry of Ediff Sessions::  Keeping track of multiple Ediff sessions.
* Session Groups::              Comparing and merging directories.
* Remote and Compressed Files::  You may want to know about this.
* Customization::               How to make Ediff work the way YOU want.
* Credits::                     Thanks to those who helped.
* Index::
File: ediff,  Node: Introduction,  Next: Major Entry Points,  Prev: Top,  Up: Top
Introduction
************
   Ediff provides a convenient way for simultaneous browsing through
the differences between a pair (or a triple) of files or buffers.  The
files being compared, file-A, file-B, and file-C (if applicable) are
shown in separate windows (side by side, one above the another, or in
separate frames), and the differences are highlighted as you step
through them.  You can also copy difference regions from one buffer to
another (and recover old differences if you change your mind).
   Another powerful feature is the ability to merge a pair of files
into a third buffer. Merging with an ancestor file is also supported.
Furthermore, Ediff is equipped with directory-level capabilities that
allow the user to conveniently launch browsing or merging sessions on
groups of files in two (or three) different directories.
   In addition, Ediff can apply a patch to a file and then let you step
though both files, the patched and the original one, simultaneously,
difference-by-difference.  You can even apply a patch right out of a
mail buffer, i.e., patches received by mail don't even have to be
saved.  Since Ediff lets you copy differences between buffers, you can,
in effect, apply patches selectively (i.e., you can copy a difference
region from `file_orig' to `file', thereby undoing any particular patch
that you don't like).
   Ediff even understands multi-file patches and can apply them
interactively!  (Ediff can recognize multi-file patches only if they
are in the context or GNU unified format. All other patches are treated
as 1-file patches. Ediff is [hopefully] using the same algorithm as
patch to determine which files need to be patched.)
   Ediff is aware of version control, which lets you compare files with
their older versions. Ediff also works with remote and compressed
files, automatically ftp'ing them over and uncompressing them.  *Note
Remote and Compressed Files::, for details.
   This package builds upon ideas borrowed from Emerge and several
Ediff's functions are adaptations from Emerge.  Although Ediff subsumes
Emerge, much of the functionality of Ediff is influenced by Emerge.
The architecture and the interface are, of course, drastically
different.
File: ediff,  Node: Major Entry Points,  Next: Commands,  Prev: Introduction,  Up: Top
Major Entry Points
******************
   Ediff can be invoked interactively using the following functions,
which can be run either from the minibuffer or from the menu bar. In
the menu bar, all Ediff's entry points belong to three submenus of the
Tools menu: Compare, Merge, and Apply Patch.
`ediff-files'
`ediff'
     Compare two files.
`ediff-buffers'
     Compare two buffers.
`ediff-files3'
`ediff3'
     Compare three files.
`ediff-buffers3'
     Compare three buffers.
`edirs'
`ediff-directories'
     Compare files common to two directories.
`edirs3'
`ediff-directories3'
     Compare files common to three directories.
`edir-revisions'
`ediff-directory-revisions'
     Compare versions of files in a given directory. Ediff selects only
     the files that are under version control.
`edir-merge-revisions'
`ediff-merge-directory-revisions'
     Merge versions of files in a given directory. Ediff selects only
     the files that are under version control.
`edir-merge-revisions-with-ancestor'
`ediff-merge-directory-revisions-with-ancestor'
     Merge versions of files in a given directory using other versions
     as ancestors. Ediff selects only the files that are under version
     control.
`ediff-windows-wordwise'
     Compare windows word-by-word.
`ediff-windows-linewise'
     Compare windows line-by-line.
`ediff-regions-wordwise'
     Compare regions word-by-word.
`ediff-regions-linewise'
     Compare regions line-by-line.
`ediff-revision'
     Compare versions of the current buffer, if the buffer is visiting
     a file under version control.
`ediff-patch-file'
`epatch'
     Patch a file, then compare.
`ediff-patch-buffer'
`epatch-buffer'
     Patch auffer, then compare.
`ediff-merge-files'
`ediff-merge'
     Merge two files.
`ediff-merge-files-with-ancestor'
`ediff-merge-with-ancestor'
     Like `ediff-merge', but with a third ancestor file.
`ediff-merge-buffers'
     Merge two buffers.
`ediff-merge-buffers-with-ancestor'
     Same but with ancestor.
`edirs-merge'
`ediff-merge-directories'
     Merge files common to two directories.
`edirs-merge-with-ancestor'
`ediff-merge-directories-with-ancestor'
     Same but using files in a third directory as ancestors.
`ediff-merge-revisions'
     Merge two versions of the file visited by the current buffer.
`ediff-merge-revisions-with-ancestor'
     Same but with ancestor.
If you want Ediff to be loaded from the very beginning of your Emacs
session, you should put this line in your `~/.emacs' file:
     (require 'ediff)
Otherwise, Ediff will be loaded automatically when you use one of the
above functions, either directly or through the menus.
   When the above functions are invoked, they prompt the user for the
information they need--typically the files or buffers to compare or
patch. Ediff tries to be smart about these prompts. For instance, in
comparing/merging files, it will offer the visible buffers as defaults.
In prompting for files, if the user enters a directory, the previously
input file name will be appended to that directory. In addition, if the
variable `ediff-use-last-dir' is not `nil', Ediff will offer previously
entered directories as defaults (which will be maintained separately
for each type of file, A, B, or C).
   All the above functions use the POSIX `diff' program to find
differences between two files.  They process the `diff' output and
display it in a convenient form.  At present, Ediff understands only the
plain output from diff.  Options such as `-c' are not supported, nor is
the format produced by incompatible file comparison programs such as
the VMS version of `diff'.
   The functions `ediff-files', `ediff-buffers', `ediff-files3',
`ediff-buffers3' first display the coarse, line-based difference
regions, as reported by the `diff' program.  Since diff may report
fairly large chunks of text as being different, even though the
difference may be localized to just a few words or even to the white
space or line breaks, Ediff further *refines* the regions to indicate
which exact words differ.  If the only difference is in the white space
and line breaks, Ediff says so.
   On a color display, fine differences are highlighted with color; on a
monochrome display, they are underlined.  *Note Highlighting Difference
Regions::, for information on how to customize this.
   The functions `ediff-windows-wordwise', `ediff-windows-linewise',
`ediff-regions-wordwise' and `ediff-regions-linewise' do comparison on
parts of existing Emacs buffers.  Since `ediff-windows-wordwise' and
`ediff-regions-wordwise' are intended for relatively small segments of
buffers, comparison is done on the basis of words rather than lines.
No refinement is necessary in this case.  These commands are recommended
only for relatively small regions (perhaps, up to 100 lines), because
these functions have a relatively slow startup.
   To compare large regions, use `ediff-regions-linewise'.  This
command displays differences much like `ediff-files' and
`ediff-buffers'.
   The functions `ediff-patch-file' and `ediff-patch-buffer' apply a
patch to a file or a buffer and then run Ediff on these buffers,
displaying the difference regions.
   The entry points `ediff-directories', `ediff-merge-directories',
etc., provide a convenient interface for comparing and merging files in
different directories. The user is presented with Dired-like interface
from which one can run a group of related Ediff sessions.
   For files under version control, `ediff-revisions' lets you compare
the file visited by the current buffer to one of its checked-in
versions.  You can also compare two checked-in versions of the visited
file.  Moreover, the functions `ediff-directory-revisions',
`ediff-merge-directory-revisions', etc., let you run a group of related
Ediff sessions by taking a directory and comparing (or merging)
versions of files in that directory.
File: ediff,  Node: Commands,  Next: Registry of Ediff Sessions,  Prev: Major Entry Points,  Up: Top
Commands
********
   All Ediff commands are displayed in a quick help window, unless you
type `?' to shrink the window to just one line.  You can redisplay the
help window by typing `?' again.  In this section we comment only on
the features that cannot be readily deduced from the quick help window.
You can always type `E' in the control window to display this manual.
   Many Ediff commands take numeric prefix arguments.  For instance, if
you type a number, say 3, and then `j' (`ediff-jump-to-difference'),
Ediff moves to the third difference region.   Typing 3 and then `a'
(`ediff-diff-to-diff') copies the 3d difference region from buffer A to
buffer B.  Typing `b' does copying in the opposite direction.  (In
3-way comparison mode, the commands for copying are `ab', `ba', `ca',
etc.) Likewise, 4 followed by `ra' restores the 4th difference region
in buffer A (if it was previously saved as a result of copying from,
say, buffer B to A).
   Some commands take negative prefix arguments as well.  For instance,
typing `-' and then `j' will take Ediff to the last difference. Typing
`-2' then `j' takes Ediff to to the penultimate difference region, etc.
   Without the prefix argument, all commands operate on the current
selected difference region.  You can select any difference region as
the current one using other Ediff commands.
   For some commands, the value of the prefix argument is immaterial.
However, if supplied, the prefix argument modifies the command.  For
instance, normally the commands `ga'/`gb'/`gc'
(`ediff-jump-to-difference-at-point') causes Ediff to jump to the
difference region that is closest to the point in a specified buffer
(the buffer, A, B, or C, is specified by the last character of the
command, i.e., for `gb', the specified buffer is B).  However, with a
prefix argument, Ediff would position all these buffers around the area
indicated by the current point in the specified buffer: if the point is
inside a difference region, then the buffers will be positioned at this
difference region. If the point is not in any difference region, then
it is in an area where all buffers agree with each other. In this case,
all buffers will be positioned so that they would display this area.
   The total number of differences and the current difference number are
always displayed in the mode line of the control window.
   If, after making changes to buffers A, B, or C, you decide to save
them, it is best to use `ediff-save-buffer', which is bound to `wa',
`wb', and `wc' (`wa' will save buffer A, `wb' saves buffer B, etc.).
   Typing `wd' saves the output from the `diff' utility to a file, so
you can later refer to it. With prefix argument, this command saves the
plain output from `diff' (see `ediff-diff-program' and
`ediff-diff-options'). Without the argument, it saves customized `diff'
output (see `ediff-custom-diff-program' and
`ediff-custom-diff-options'), if it is available.
   Instead of saving it, `diff' output can be *displayed* using the
command `D'. Without the prefix argument, it displays the customized
`diff' output of the session.  With the prefix argument, it displays
the plain `diff' output If either of the `diff' outputs is unavailable
(because it wasn't generated or the user killed the respective buffer),
then Ediff will try to display the other `diff' output.  If none is
available, a warning is issued.
   The command `z' suspends the current ediff session. It hides the
control buffer and the variants. The easiest way to resume a suspended
Ediff session is through the registry of active sessions.  *Note
Registry of Ediff Sessions::, for details.
   The command `q' quits the current Ediff session. With a prefix
argument, it will ask the user whether to delete the variant buffers.
   The command `s' is used only for merging.  It shrinks window C (the
merge window) to its minimal size, thereby exposing as much of buffers A
and B as possible.  This command is intended only for temporary viewing;
therefore, Ediff restores window C to its original size whenever it
makes any other change in the window configuration.  Typing `s' again
also restores the original size of window C.  However, recentering and
jumping to a difference does not affect window C's size.
   With a positive prefix argument, the command `s' makes the merge
window, window C, slightly taller. With `-' or a negative prefix
argument, `s' makes window C slightly shorter.
   Another command used only for merging is `+'.  Its effect is to
combine the current difference regions of buffers A and B and put the
combination into the merge buffer. *Note Merging and diff3::,
specifically, the variables `ediff-combine-diffs' and
`ediff-combination-pattern'.
   In merge mode, Ediff uses a default variant (one of the two files
being merged) when it cannot decide which of the difference regions
(that of buffer A or buffer B) should be copied into the merge buffer.
You might decide to use the other variant instead.  To facilitate this,
Ediff has a command, bound to `&', which selects another default
variant for the current difference and subsequent differences.  You can
specify as the new default any of `default-A', `default-B', or
`combined'.  *Note Merging and diff3::, for details.
   Such repeated merging affects only difference regions that have
default-A/B status, and only if they were not changed with respect to
their originals.
   Some commands are not bound to any key:
`eregistry'
`ediff-show-registry'
     This command brings up the registry of active Ediff sessions.
     Ediff registry is a useful device that can be used for resuming
     Ediff sessions when the user switched to some other work before
     finishing a comparison or merging job.  It is also useful for
     switching between multiple active Ediff sessions that are run at
     the same time. The function `eregistry' is an alias for
     `ediff-show-registry'.
`ediff-toggle-multiframe'
     Changes the display from the multi-frame mode (where the quick
     help window is in a separate frame) to the single-frame mode
     (where all Ediff buffers share the same frame), and vice versa.
`ediff-revert-buffers-then-recompute-diffs'
     This command reverts the buffers you are comparing and recomputes
     their differences.  It is useful when, after making changes, you
     decided to make a fresh start, or if at some point you changed the
     files being compared but want to discard any changes to comparison
     buffers that were done since then.
     This command normally asks for confirmation before reverting files.
     With a prefix argument, it reverts files without asking.
`ediff-profile'
     Ediff has an admittedly primitive (but useful) facility for
     profiling Ediff's commands.  It is meant for Ediff
     maintenance--specifically, for making it run faster.  The function
     `ediff-profile' toggles profiling of ediff commands.
File: ediff,  Node: Registry of Ediff Sessions,  Next: Session Groups,  Prev: Commands,  Up: Top
Registry of Ediff Sessions
**************************
   Ediff maintains a registry of all its invocations that are still
*active*. This feature is very convenient for switching among active
Ediff sessions or for quickly restarting a suspended Ediff session.
   The focal point of this activity is a buffer called **Ediff
Registry**. You can display this buffer by typing `R' in any Ediff
Control Buffer or Session Group Buffer (*note Session Groups::.), or by
typing `M-x eregistry' into the Minibuffer.  The latter would be the
fastest way to bring up the registry buffer if no control or group
buffer is displayed in any of the visible Emacs windows.  If you are in
a habit of running multiple long Ediff sessions and often need to
suspend, resume, or switch between them, it may be a good idea to have
the registry buffer permanently displayed in a separate, dedicated
window.
   The registry buffer has several convenient key bindings.  For
instance, clicking mouse button 2 or typing `RET' or `v' over any
session record resumes that session.  Session records in the registry
buffer provide a fairly complete description of each session, so it is
usually easy to identify the right session to resume.
   Other useful commands are bound to `SPC' (next registry record) and
`DEL' (previous registry record). There are other commands as well, but
you don't need to memorize them, since they are listed at the top of
the registry buffer.
File: ediff,  Node: Session Groups,  Next: Remote and Compressed Files,  Prev: Registry of Ediff Sessions,  Up: Top
Session Groups
**************
   Several major entries of Ediff perform comparison and merging on
directories.  On entering `ediff-directories', `ediff-directories3',
`ediff-merge-directories', `ediff-merge-directories-with-ancestor',
`ediff-directory-revisions', `ediff-merge-directory-revisions', or
`ediff-merge-directory-revisions-with-ancestor', the user is presented
with a Dired-like buffer that lists files common to the directories
involved along with their sizes. (The list of common files can be
further filtered through a regular expression, which the user is
prompted for.) We call this buffer *Session Group Panel* because all
Ediff sessions associated with the listed files will have this buffer
as a common focal point.
   Clicking button 2 or typing `RET' or `v' over a record describing
files invokes Ediff in the appropriate mode on these files. You can
come back to the session group buffer associated with a particular
invocation of Ediff by typing `M' in Ediff control buffer of that
invocation.
   Many commands are available in the session group buffer; some are
applicable only for certain types of work. The relevant commands are
always listed at the top of each session group buffer, so there is no
need to memorize them.
   In directory comparison or merging, a session group panel displays
only the files common to all directories involved. The differences are
kept in a separate buffer and are conveniently displayed by typing `D'
to the corresponding session group panel. Thus, as an added benefit,
Ediff can be used to compare the contents of up to three directories.
   Session records in session group panels are also marked with `+', for
active sessions, and with `-', for finished sessions.
   Sometimes, it is convenient to exclude certain session records from
a group.  Usually this happens when the user doesn't intend to run
Ediff of certain files in the group, and the corresponding session
records just add clutter to the session group buffer. To help alleviate
this problem, the user can type `h' to mark a session as a candidate
for exclusion and `x' to actually hide the marked sessions. There
actions are reversible: with a prefix argument, `h' unmarks the session
under the cursor, and `x' brings the hidden sessions into the view (`x'
doesn't unmark them, though, so the user has to explicitly unmark the
sessions of interest).
   Group sessions also understand the command `m', which marks sessions
for future operations (other than hiding) on a group of sessions. At
present, the only such group-level operation is the creation of a
multi-file patch.
   A multi-file patch is a concatenated output of several runs of the
Unix `diff' command (some versions of `diff' let you create a
multi-file patch in just one run).  In a session group buffer created in
response to `ediff-directories' or `ediff-directory-revisions', the
user can type `P' to create a multi-file patch of marked sessions
(which must be marked using the `m' command).  Ediff then will display
a buffer containing the patch.  In an `ediff-directories' session, it
is enough to just mark the requisite sessions. In
`ediff-directory-revisions' revisions, the marked sessions must also be
active, or else Ediff will refuse to produce a multi-file patch. This is
because, in the latter-style sessions, there are many ways to create
diff output, and it is easier to handle by running Ediff on the inactive
sessions.
File: ediff,  Node: Remote and Compressed Files,  Next: Customization,  Prev: Session Groups,  Up: Top
Remote and Compressed Files
***************************
   Ediff works with remote, compressed, and encrypted files.  Ediff
supports `ange-ftp.el', `jka-compr.el', `uncompress.el' and
`crypt++.el', but it may work with other similar packages as well.
This means that you can compare files residing on another machine, or
you can apply a patch to a file on another machine.  Even the patch
itself can be a remote file!
   When patching compressed or remote files, Ediff does not rename the
source file (unlike what the `patch' utility would usually do).
Instead, the source file retains its name and the result of applying
the patch is placed in a temporary file that has the suffix `_patched'
attached.  Generally, this applies to files that are handled using
black magic, such as special file handlers (ange-ftp and some
compression and encryption packages all use this method).
   Regular files are treated by the `patch' utility in the usual manner,
i.e., the original is renamed into `source-name.orig' and the result of
the patch is placed into the file source-name. (Ediff `_orig' on
systems like VMS, DOS, etc.)
File: ediff,  Node: Customization,  Next: Credits,  Prev: Remote and Compressed Files,  Up: Top
Customization
*************
   Ediff has a rather self-explanatory interface, and in most cases you
won't need to change anything.  However, should the need arise, there
are extensive facilities to change the default behavior.
   Most of the customization can be done by setting various variables
in the `.emacs' file. Some customization (mostly window-related
customization and faces) can be done by putting appropriate lines in
`.Xdefaults', `.xrdb', or whatever X resource file is in use.
   With respect to the latter, please note that the X resource for
Ediff customization is `Ediff', *not* `emacs'.  *Note Window and Frame
Configuration::, *Note Highlighting Difference Regions::, for further
details. Please also refer to Emacs manual for the information on how
to set Emacs X resources.
* Menu:
* Hooks::                       Customization via the hooks.
* Quick Help::                  How to customize Ediff's quick help feature.
* Window and Frame Configuration::  Controlling the way Ediff displays things.
* Selective Browsing::          Advanced browsing through difference regions.
* Highlighting Difference Regions::  Controlling highlighting.
* Narrowing::                   Comparing regions, windows, etc.
* Refinement of Difference Regions::  How to control the refinement process.
* Patch and Diff Programs::     Changing the utilities that compute differences
                                and apply patches.
* Merging and diff3::           How to customize Ediff in its Merge Mode.
* Support for Version Control::  Changing the version control package.
                                 You are not likely to do that.
* Customizing the Mode Line::   Changing the look of the mode line in Ediff.
* Miscellaneous::               Other customization.
* Notes on Heavy-duty Customization::  Customization for the gurus.
File: ediff,  Node: Hooks,  Next: Quick Help,  Prev: Customization,  Up: Customization
Hooks
=====
   The bulk of customization can be done via the following hooks:
`ediff-load-hook'
     This hook can be used to change defaults after Ediff is loaded.
`ediff-keymap-setup-hook'
     This hook can be used to alter bindings in Ediff's keymap. These
     hooks are run right after the default bindings are set but before
     `ediff-load-hook'.  The regular user needs not be concerned with
     this hook--it is provided for implementors of other Emacs packages
     built on top of Ediff.
`ediff-before-setup-windows-hook'
`ediff-after-setup-windows-hook'
     These two hooks are called before and after Ediff sets up its
     window configuration.  Can be used to save the configuration that
     existed before Ediff starts or for whatever other purposes.
`ediff-suspend-hook'
`ediff-quit-hook'
     These two hooks are run when you suspend or quit Ediff.  They can
     be used to set desired window configurations, delete files Ediff
     didn't want to clean up after exiting, etc.
     By default, `ediff-quit-hook' holds one hook function,
     `ediff-cleanup-mess', which cleans after Ediff, as appropriate in
     most cases.  You probably won't want to change it, but you might
     want to add other hook functions.
     Keep in mind that hooks executing before `ediff-cleanup-mess' start
     in `ediff-control-buffer;' they should also leave
     `ediff-control-buffer' as the current buffer when they finish.
     Hooks that are executed after `ediff-cleanup-mess' should expect
     the current buffer be either buffer A or buffer B.
     `ediff-cleanup-mess' doesn't kill the buffers being compared or
     merged (see `ediff-cleanup-hook', below).
`ediff-cleanup-hook'
     This hook is run just before `ediff-quit-hook'.  This is a good
     place to do various cleanups, such as deleting the variant buffers.
     Ediff provides a function, `ediff-janitor', as one such possible
     hook, which you can add to `ediff-cleanup-hook' with `add-hooks'.
     This function kills buffers A, B, and, possibly, C, if these
     buffers aren't modified. In merge jobs, buffer C is never deleted.
     However, the side effect of using this function is that you may
     not be able to compare the same buffer in two separate Ediff
     sessions: quitting one of them will delete this buffer in another
     session as well.
`ediff-before-setup-control-frame-hook'
`ediff-after-setup-control-frame-hook'
     These two hooks run before and after Ediff sets up the control
     frame.  They can be used to relocate Ediff control frame when
     Ediff runs in a multiframe mode (i.e., when the control buffer is
     in its own dedicated frame).  Be aware that many variables that
     drive Ediff are local to Ediff Control Panel
     (`ediff-control-buffer'), which requires special care in writing
     these hooks.  Take a look at `ediff-default-suspend-hook' and
     `ediff-default-quit-hook' to see what's involved.
`ediff-startup-hook'
     This hook is run at the end of Ediff startup.
`ediff-select-hook'
     This hook is run after Ediff selects the next difference region.
`ediff-unselect-hook'
     This hook is run after Ediff unselects the current difference
     region.
`ediff-prepare-buffer-hook'
     This hook is run for each Ediff buffer (A, B, C) right after the
     buffer is arranged.
`ediff-display-help-hook'
     Ediff runs this hook each time after setting up the help message.
     It can be used to alter the help message for custom packages that
     run on top of Ediff.
`ediff-mode-hook'
     This hook is run just after Ediff mode is set up in the control
     buffer. This is done before any Ediff window is created. You can
     use it to set local variables that alter the look of the display.
`ediff-registry-setup-hook'
     Hooks run after setting up the registry for all active Ediff
     session.  *Note Session Groups::, for details.
`ediff-session-group-setup-hook'
     Hooks run after setting up a control panel for a group of related
     Ediff sessions. *Note Session Groups::, for details.
File: ediff,  Node: Quick Help,  Next: Window and Frame Configuration,  Prev: Hooks,  Up: Customization
Quick Help
==========
   Ediff provides quick help using its control panel window. Since this
window takes a fair share of the screen real estate, you can toggle it
off by typing `?'.  The control window will then shrink to just one
line and a mode line, displaying a short help message.
   The variable `ediff-use-long-help-message' tells Ediff whether you
use the short message or the long one.  By default, it is set to `nil',
meaning that the short message is used.  Set this to `t', if you want
Ediff to use the long message by default. This property can always be
changed interactively, by typing `?' into Ediff Control Buffer.
   If you want to change the appearance of the help message on a
per-buffer basis, you must use `ediff-startup-hook' to change the value
of the variable `ediff-help-message', which is local to
`ediff-control-buffer'.
File: ediff,  Node: Window and Frame Configuration,  Next: Selective Browsing,  Prev: Quick Help,  Up: Customization
Window and Frame Configuration
==============================
   On a non-windowing display, Ediff sets things up in one frame,
splitting it between a small control window and the windows for buffers
A, B, and C.  The split between these windows can be horizontal or
vertical, which can be changed interactively by typing `|' while the
cursor is in the control window.
   On a window display, Ediff sets up a dedicated frame for Ediff
Control Panel and then it chooses windows as follows: If one of the
buffers is invisible, it is displayed in the currently selected frame.
If a buffer is visible, it is displayed in the frame where it is
visible.  If, according to the above criteria, the two buffers fall
into the same frame, then so be it--the frame will be shared by the
two.  The same algorithm works when you type `C-l' (`ediff-recenter'),
`p' (`ediff-previous-difference'), `n' (`ediff-next-difference'), etc.
   The above behavior also depends on whether the current frame is
splittable, dedicated, etc. Unfortunately, the margin is too small to
present this remarkable algorithm.
   The bottom line of all this is that you can compare buffers in one
frame or in different frames.  The former is done by default, while the
latter can be achieved by arranging buffers A, B (and C, if applicable)
to be seen in different frames.  Ediff respects these arrangements,
automatically adapting itself to the multi-frame mode.
   Ediff uses the following variables to set up its control panel
(a.k.a. control buffer, a.k.a. quick help window):
`ediff-control-frame-parameters'
     You can change or augment this variable including the font, color,
     etc.  The X resource name of Ediff Control Panel frames is
     `Ediff'.  Under X-windows, you can use this name to set up
     preferences in your `~/.Xdefaults', `~/.xrdb', or whatever X
     resource file is in use. Usually this is preferable to changing
     `ediff-control-frame-parameters' directly.  For instance, you can
     specify in `~/.Xdefaults' the color of the control frame using the
     resource `Ediff*background'.
     In general, any X resource pertaining the control frame can be
     reached via the prefix `Ediff*'.
`ediff-control-frame-position-function'
     The preferred way of specifying the position of the control frame
     is by setting the variable `ediff-control-frame-position-function'
     to an appropriate function.  The default value of this variable is
     `ediff-make-frame-position'. This function places the control
     frame in the vicinity of the North-East corner of the frame
     displaying buffer A.
   The following variables can be used to adjust the location produced
by `ediff-make-frame-position' and for related customization.
`ediff-narrow-control-frame-leftward-shift'
     Specifies the number of characters for shifting the control frame
     from the rightmost edge of frame A when the control frame is
     displayed as a small window.
`ediff-wide-control-frame-rightward-shift'
     Specifies the rightward shift of the control frame from the left
     edge of frame A when the control frame shows the full menu of
     options.
`ediff-control-frame-upward-shift'
     Specifies the number of pixels for the upward shift of the control
     frame.
`ediff-prefer-iconified-control-frame'
     If this variable is `t', the control frame becomes iconified
     automatically when you toggle the quick help message off.  This
     saves valuable real estate on the screen.  Toggling help back will
     deiconify the control frame.
     To start Ediff with an iconified Control Panel, you should set this
     variable to `t' and `ediff-prefer-long-help-message' to `nil'
     (*note Quick Help::.).  This behavior is useful only if the window
     manager is TWM or a derivative. Also, this doesn't work under
     XEmacs, since this editor ignores input from icons.
   To make more creative changes in the way Ediff sets up windows, you
can rewrite the function `ediff-setup-windows'.  However, we believe
that detaching Ediff Control Panel from the rest and making it into a
separate frame offers an important opportunity by allowing you to
iconify that frame.  Under Emacs, the icon will usually accept all of
the Ediff commands, but will free up valuable real estate on your screen
(this may depend on the window manager, though).  Iconifying won't do
any good under XEmacs since XEmacs icons are not sensitive to keyboard
input.  The saving grace is that, even if not iconified, the control
frame is very small, smaller than some icons, so it does not take much
space in any case.
   The following variable controls how windows are set up:
`ediff-window-setup-function'
     The multiframe setup is done by the
     `ediff-setup-windows-multiframe' function, which is the default on
     windowing displays.  The plain setup, one where all windows are
     always in one frame, is done by `ediff-setup-windows-plain', which
     is the default on a non-windowing display (or in an xterm window).
     In fact, under Emacs, you can switch freely between these two
     setups by executing the command `ediff-toggle-multiframe' using
     the Minibuffer.
     If you don't like any of these setups, write your own function.
     See the documentation for `ediff-window-setup-function' for the
     basic guidelines.  However, writing window setups is not easy, so
     you should first take a close look at `ediff-setup-windows-plain'
     and `ediff-setup-windows-multiframe'.
   You can run multiple Ediff sessions at once, by invoking Ediff
several times without exiting previous Ediff sessions.  Different
sessions may even operate on the same pair of files.
   Each session has its own Ediff Control Panel and all the regarding a
particular session is local to the associated control panel buffer.  You
can switch between sessions by suspending one session and then switching
to another control panel.  (Different control panel buffers are
distinguished by a numerical suffix, e.g., `Ediff Control Panel<3>'.)
File: ediff,  Node: Selective Browsing,  Next: Highlighting Difference Regions,  Prev: Window and Frame Configuration,  Up: Customization
Selective Browsing
==================
   Sometimes it is convenient to be able to step through only some
difference regions, those that satisfy certain regular expressions, and
to ignore all others.  On other occasions, you may want to ignore
difference regions that satisfy some regular expressions, and to look
only at the rest.
   The commands `#f' and `#h' let you do precisely this.
   Typing `#f' lets you specify regular expressions that match
difference regions you want to focus on.  We shall call these regular
expressions REGEXP-A, REGEXP-B and REGEXP-C.  Ediff will then start
stepping through only those difference regions where the region in
buffer A matches REGEXP-A and/or the region in buffer B matches
REGEXP-B, etc.  Whether `and' or `or' will be used depends on how you
respond to a question.
   When scanning difference regions for the aforesaid regular
expressions, Ediff narrows the buffers to those regions. This means
that you can use the expressions `\`' and `\'' to tie search to the
beginning or end of the difference regions.
   On the other hand, typing `#h' lets you specify (hide) uninteresting
regions. That is, if a difference region in buffer A matches REGEXP-A,
the corresponding region in buffer B matches REGEXP-B and (if
applicable) buffer-C's region matches REGEXP-C, then the region will be
ignored by the commands `n'/SPC (`ediff-next-difference') and `p'/DEL
(`ediff-previous-difference') commands.
   Typing `#f' and `#h' toggles selective browsing on and off.
   Note that selective browsing affects only `ediff-next-difference'
and `ediff-previous-difference', i.e., the commands `n'/SPC and
`p'/DEL.  `#f' and `#h' do not change the position of the point in the
buffers.  And you can still jump directly (using `j')  to any numbered
difference.
   Users can supply their own functions to specify how Ediff should do
selective browsing. To change the default Ediff function, add a
function to `ediff-load-hook' which will do the following assignments:
     (setq ediff-hide-regexp-matches-function 'your-hide-function)
     (setq ediff-focus-on-regexp-matches-function 'your-focus-function)
   *Useful hint*: To specify a regexp that matches everything, don't
simply type RET in response to a prompt. Typing RET tells Ediff to
accept the default value, which may not be what you want. Instead, you
should enter something like ^ or $. These match every line.
   You can use the status command, `i', to find out whether selective
browsing is currently in use.
   The regular expressions you specified are kept in the local variables
`ediff-regexp-focus-A', `ediff-regexp-focus-B', `ediff-regexp-focus-C',
`ediff-regexp-hide-A', `ediff-regexp-hide-B', `ediff-regexp-hide-C'.
Their default value is the empty string (i.e., nothing is hidden or
focused on).  To change the default, set these variables in `.emacs'
using `setq-default'.
   In addition to the ability to ignore regions that match regular
expressions, Ediff can be ordered to start skipping over certain
"inessential" regions.  This is controlled by the following variable:
`ediff-ignore-similar-regions'
     If `t', causes Ediff to skip over difference regions that deemed
     inessential, i.e., where the only differences are those in the
     white space and newlines.
   *Note:* In order for this feature to work, auto-refining of
difference regions must be on, since otherwise Ediff won't know if there
are fine differences between regions.  On devices where Emacs can
display faces, auto-refining is a default, but it is not turned on by
default on text-only terminals.  In that case, you must explicitly turn
auto-refining on (such as, by typing `@').
   *Reassurance:* If many inessential regions appear in a row, Ediff may
take a long time to jump to the next region because it has to compute
fine differences of all intermediate regions.  This delay does not
indicate any problem.
File: ediff,  Node: Highlighting Difference Regions,  Next: Narrowing,  Prev: Selective Browsing,  Up: Customization
Highlighting Difference Regions
===============================
   The following variables control the way Ediff highlights difference
regions:
`ediff-before-flag-bol'
`ediff-after-flag-eol'
`ediff-before-flag-mol'
`ediff-after-flag-mol'
     These variables hold strings that Ediff uses to mark the beginning
     and the end of the differences found in files A, B, and C on
     devices where Emacs cannot display faces. Ediff uses different
     flags to highlight regions that begin/end at the beginning/end of
     a line or in a middle of a line.
`ediff-current-diff-face-A'
`ediff-current-diff-face-B'
`ediff-current-diff-face-C'
     Ediff uses these faces to highlight current differences on devices
     where Emacs can display faces.  These and subsequently described
     faces can be set either in `.emacs' or in `.Xdefaults'. The X
     resource for Ediff is `Ediff', *not* `emacs'. Please refer to
     Emacs manual for the information on how to set X resources.
`ediff-fine-diff-face-A'
`ediff-fine-diff-face-B'
`ediff-fine-diff-face-C'
     Ediff uses these faces to show the fine differences between the
     current differences regions in buffers A, B, and C, respectively.
`ediff-even-diff-face-A'
`ediff-even-diff-face-B'
`ediff-even-diff-face-C'
`ediff-odd-diff-face-A'
`ediff-odd-diff-face-B'
`ediff-odd-diff-face-C'
     Non-current difference regions are displayed using these
     alternating faces. The odd and the even faces are actually
     identical on monochrome displays, because without colors options
     are limited.  So, Ediff uses italics to highlight non-current
     differences.
`ediff-force-faces'
     Ediff generally can detect when Emacs is running on a device where
     it can use highlighting with faces. However, if it fails to
     determine that faces can be used, the user can set this variable
     to `t' to make sure that Ediff uses faces to highlight differences.
`ediff-highlight-all-diffs'
     Indicates whether--on a window system--Ediff should highlight
     differences using inserted strings (as on a text-only terminal) or
     using colors and highlighting.  Normally, Ediff highlights all
     differences, but the selected difference is highlighted more
     visibly.  One can cycle through various modes of highlighting by
     typing `h'.  By default, Ediff starts in the mode where all
     difference regions are highlighted.  If you prefer to start in the
     mode where unselected differences are not highlighted, you should
     set `ediff-highlight-all-diffs' to `nil'.  Type `h' to restore
     highlighting of all differences.
     Ediff lets you switch between the two modes of highlighting.  That
     is, you can switch interactively from highlighting using faces to
     highlighting using string flags, and back.  Of course, switching
     has effect only under a windowing system.  On a text-only terminal
     or in an xterm window, the only available option is highlighting
     with strings.
If you want to change the above variables, you must do it *before*
Ediff is loaded.
   There are two ways to change the default setting for highlighting
faces: either change the variables, as shown here,
     (setq ediff-current-diff-face-A 'bold-italic)
or here,
     (setq ediff-current-diff-face-A
     (copy-face 'bold-italic 'ediff-current-diff-face-A))
or modify the defaults selectively:
     (add-hook 'ediff-load-hook
               (function (lambda ()
                           (set-face-foreground
                             ediff-current-diff-face-B "blue")
                           (set-face-background
                             ediff-current-diff-face-B "red")
                           (make-face-italic
                             ediff-current-diff-face-B))))
   You may also want to take a look at how the above faces are defined
in the source code of Ediff.
   *Note:* it is not recommended to use `internal-get-face' (or
`get-face' in XEmacs) when defining Ediff's faces, since this may cause
problems when there are several frames with different font sizes.
Instead, use `copy-face' or `set/make-face-...' as shown above.
File: ediff,  Node: Narrowing,  Next: Refinement of Difference Regions,  Prev: Highlighting Difference Regions,  Up: Customization
Narrowing
=========
   If buffers being compared are narrowed at the time of invocation of
Ediff, `ediff-buffers' will preserve the narrowing range.  However, if
`ediff-files' is invoked on the files visited by these buffers, that
widens the buffers, since this command is defined to compare the entire
files.
   Calling `ediff-regions-linewise' or `ediff-windows-linewise', or the
corresponding `-wordwise' commands, narrows the buffers being compared
(corresponding to the regions being compared).  The original accessible
ranges are restored when you quit Ediff.  During the command, you can
toggle this narrowing on and off with the `%' command.
   These two variables control this narrowing behavior:
`ediff-start-narrowed'
     If `t', Ediff narrows the display to the appropriate range when it
     is invoked with an `ediff-regions...' or `ediff-windows...'
     command.  If `nil', these commands do not automatically narrow,
     but you can still toggle narrowing on and off by typing `%'.
`ediff-quit-widened'
     Controls whether on quitting Ediff should restore the accessible
     range that existed before the current invocation.
File: ediff,  Node: Refinement of Difference Regions,  Next: Patch and Diff Programs,  Prev: Narrowing,  Up: Customization
Refinement of Difference Regions
================================
   Ediff has variables to control the way fine differences are
highlighted.  This feature gives you control over the process of
refinement.  Note that refinement ignores spaces, tabs, and newlines.
`ediff-auto-refine'
     This variable controls whether fine differences within regions are
     highlighted automatically ("auto-refining").  The default is yes
     (`on').
     On a slow machine, automatic refinement may be painful.  In that
     case, you can turn auto-refining on or off interactively by typing
     `@'.  You can also turn off display of refining that has already
     been done.
     When auto-refining is off, fine differences are shown only for
     regions for which these differences have been computed and saved
     before.  If auto-refining and display of refining are both turned
     off, fine differences are not shown at all.
     Typing `*' computes and displays fine differences for the current
     difference region, regardless of whether auto-refining is turned
     on.
`ediff-auto-refine-limit'
     If auto-refining is on, this variable limits the size of the
     regions to be auto-refined.  This guards against the possible
     slowdown that may be caused by extraordinary large difference
     regions.
     You can always refine the current region by typing `*'.
`ediff-forward-word-function'
     This variable gives control over how fine differences are
     computed.  The value must be a Lisp function that determines how
     the current difference region should be split into words.
     Fine differences are computed by first splitting the current
     difference region into words and then passing this along to
     `ediff-diff-program'. For the default
     `ediff-forward-word-function' (which is `ediff-forward-word'), a
     word is a string consisting of letters, `-', or `_'; a string of
     punctuation symbols; a string of digits, or a string consisting of
     symbols that are neither space, nor a letter.
     This default behavior is controlled by four variables:
     `ediff-word-1', ..., `ediff-word-4'. See the on-line documentation
     for these variables and for the function `ediff-forward-word' for
     an explanation of how to modify these variables.
   Sometimes, when a region has too many differences between the
variants, highlighting of fine differences is inconvenient, especially
on color displays.  If that is the case, type `*' with a negative
prefix argument.  This unhighlights fine differences for the current
region.
   To unhighlight fine differences in all difference regions, use the
command `@'.  Repeated typing of this key cycles through three
different states: auto-refining, no-auto-refining, and no-highlighting
of fine differences.